Converted the ..image directive to ..figure. Set the figure :alt: to blank because we're adding a visible text captions.

Converted the list to section headings, added a Recommendation header, and made minor text adjustments to make the page more readable as a web page.

I checked the generated PDF and noticed it was putting one image per page that was separate from the text. The PDF generator does tend to float images out of context (which is not good). However, with text captions at least they now have some context. I adjusted the image sizes so that the first two end up on one page and the the remaining images fit with their text on one page.

The web presentation still looks with smaller images. Users can select the image and open it in a new tab if they want full size. I also set figure **:class: no-scaled-link ** since these images did not have a web link before, and I don't thing they need one now.

I think this could be reviewed now.

Arrgh!

I was Googling away looking for some reference material for how to write captions when I stumbled upon something that indicated Figures should have both alt text and a caption. I found multiple instances of this, including some tests in various screen readers and browsers.

Here's a couple of pages that did some screen reader testing:

• https://www.scottohara.me/blog/2019/01/21/how-do-you-figure.html#figures-and-screen-readers
• https://www.hassellinclusion.com/blog/figure-figcaption-extended-alternate-text-screen-readers/

I set the PR back to draft. I'll have to make another change.

Issues

1. Setting a figure caption and setting alt='' is bad for accessibility.
2. Setting align and width can cause more problems than expected. Align cause images to float. In the PDF version images can float to the next page out of context with their text. This is bad accessibility. I looked at the current PDF version of the programming tool page and the images are really big. However, they are in context with the text and in the same order as the HTML version. My attempt to pretty up the HTML and PDF by setting Align and width actually made things worse in terms of accessibility by causing images to float to other pages.
3. It may be fine to use the ..image directive as long as we include alt text. Thoughtbot says "alt descriptions should be functional; figcaption descriptions should be editorial or illustrative." If we don't need editorial or illustrative comments on the image, then the image be presented with a ..image directive.
4. If we do want to use ..figure, then we need both an :alt: tag and caption text. That alt text and caption needs to be carefully written. See the thoughtbot.com page.

I'll have to revisit the field coordinate system page. Complex images probably still need captions, but now also should have alt text. The idea of functional alt text and editorial captions may help here.

This page has good guidance IMO on how to write alt text with captions.
https://thoughtbot.com/blog/alt-vs-figcaption